/* *****************************************************************************
 * JFab (http://code.google.com/p/jfab)
 * Copyright (c) 2011 JFab.org
 * Admin jfab@jeffreythompson.net
 *
 * See the file "LICENSE.txt" for information on usage and redistribution of
 * this file, and for a DISCLAIMER OF ALL WARRANTIES.
 * *****************************************************************************/

package org.jfab.core.factory;

import org.jfab.core.collection.CGAnnotationList;
import org.jfab.core.collection.CGFieldList;
import org.jfab.core.collection.CGMethodList;
import org.jfab.core.collection.CGParameterList;
import org.jfab.core.collection.CGPropertyList;
import org.jfab.core.collection.CGTypeList;
import org.jfab.core.collection.CommentList;
import org.jfab.core.collection.MethodBodyList;
import org.jfab.core.collection.ModifierList;
import org.jfab.core.collection.ParameterNameList;
import org.jfab.core.model.CGField;
import org.jfab.core.model.CGMethod;
import org.jfab.core.model.CGMethodDeclaration;
import org.jfab.core.model.CGType;
import org.jfab.core.util.TypeParameterMap;

/**
 * Defines methods required by a code generator method factory.
 */
public interface CGMethodFactory
{
    /**
     * @param field Code generator field.
     * 
     * @return a new accessor method.
     */
    CGMethod createAccessorMethod(CGField field);

    /**
     * @param annotations Annotations.
     * @param modifiers Modifiers.
     * 
     * @return an addPropertyChangeListener() method.
     */
    CGMethod createAddPropertyChangeListenerMethod(
            CGAnnotationList annotations, ModifierList modifiers);

    /**
     * @param annotations Annotations.
     * @param modifiers Modifiers.
     * 
     * @return an addPropertyChangeListener() method.
     */
    CGMethod createAddPropertyChangeListenerNamedMethod(
            CGAnnotationList annotations, ModifierList modifiers);

    /**
     * @return a clone() method.
     */
    CGMethod createCloneMethod();

    /**
     * @param commentLines Comment lines.
     * @param annotations Annotations.
     * @param modifiers Modifiers (@see java.lang.reflect.Modifier)
     * @param returnType Return type (required).
     * @param methodName Method name (required).
     * @param parameters Parameters.
     * @param fieldName Delegate field name.
     * 
     * @return a method which uses a delegate.
     */
    CGMethod createDelegateMethod(CommentList commentLines,
            CGAnnotationList annotations, ModifierList modifiers,
            CGType returnType, String methodName, CGParameterList parameters,
            String fieldName);

    /**
     * @param classname Classname.
     * @param fields Fields.
     * 
     * @return a new equals() method.
     */
    CGMethod createEqualsMethod(String classname, CGFieldList fields);

    /**
     * @return a new <code>getInstanceFactory()</code> method.
     */
    CGMethod createGetInstanceFactoryMethod();

    /**
     * @return a getPropertyChangeSupport() method.
     */
    CGMethod createGetPropertyChangeSupportMethod();

    /**
     * @param fields Fields.
     * 
     * @return a new hashCode() method.
     */
    CGMethod createHashCodeMethod(CGFieldList fields);

    /**
     * @param referencedTypes Referenced types.
     * @param annotations Annotations.
     * @param modifiers Modifiers (@see java.lang.reflect.Modifier)
     * @param propertyType Property type.
     * @param propertyName Property name.
     * @param constructorArgs Constructor arguments.
     * 
     * @return a lazy initialization accessor method.
     */
    CGMethod createLazyInitializationAccessorMethod(CGTypeList referencedTypes,
            CGAnnotationList annotations, ModifierList modifiers,
            CGType propertyType, String propertyName,
            ParameterNameList constructorArgs);

    /**
     * @param methodDeclaration Method declaration.
     * @param methodBodyLines Method body lines.
     * 
     * @return a new code generator method.
     */
    CGMethod createMethod(CGMethodDeclaration methodDeclaration,
            MethodBodyList methodBodyLines);

    /**
     * @param referencedTypes Referenced types.
     * @param commentLines Comment lines.
     * @param annotations Annotations.
     * @param modifiers Modifiers (@see java.lang.reflect.Modifier)
     * @param returnType Return type.
     * @param methodName Method name. (required)
     * @param parameters Parameters.
     * @param throwsTypes Throws types.
     * @param methodBodyLines Method body lines.
     * 
     * @return a new code generator method.
     */
    CGMethod createMethod(CGTypeList referencedTypes, CommentList commentLines,
            CGAnnotationList annotations, ModifierList modifiers,
            CGType returnType, String methodName, CGParameterList parameters,
            CGTypeList throwsTypes, MethodBodyList methodBodyLines);

    /**
     * @param field Code generator field.
     * 
     * @return a new mutator method.
     */
    CGMethod createMutatorMethod(CGField field);

    /**
     * @param annotations Annotations.
     * @param modifiers Modifiers.
     * @param propertyType Property type.
     * @param propertyName Property name.
     * @param paramComment Parameter comment.
     * 
     * @return a mutator property change method.
     */
    CGMethod createMutatorPropertyChangeMethod(CGAnnotationList annotations,
            ModifierList modifiers, CGType propertyType, String propertyName,
            String paramComment);

    /**
     * @param field Code generator field.
     * 
     * @return a new mutator method with property change support.
     */
    CGMethod createMutatorPropertyChangeMethod(CGField field);

    /**
     * @param annotations Annotations.
     * @param modifiers Modifiers.
     * @param properties Properties.
     * @param typeParameterMap Type parameter map.
     * 
     * @return a list of new property accessor methods.
     */
    CGMethodList createPropertyAccessorMethods(CGAnnotationList annotations,
            ModifierList modifiers, CGPropertyList properties,
            TypeParameterMap typeParameterMap);

    /**
     * @param annotations Annotations.
     * @param modifiers Modifiers.
     * @param properties Properties.
     * @param typeParameterMap Type parameter map.
     * 
     * @return a list of new property mutator methods.
     */
    CGMethodList createPropertyMutatorMethods(CGAnnotationList annotations,
            ModifierList modifiers, CGPropertyList properties,
            TypeParameterMap typeParameterMap);

    /**
     * @param annotations Annotations.
     * @param modifiers Modifiers.
     * @param properties Properties.
     * 
     * @return a new collection of mutator methods for the given properties.
     */
    CGMethodList createPropertyMutatorPropertyChangeMethods(
            CGAnnotationList annotations, ModifierList modifiers,
            CGPropertyList properties);

    /**
     * @param annotations Annotations.
     * @param modifiers Modifiers.
     * 
     * @return a removePropertyChangeListener() method.
     */
    CGMethod createRemovePropertyChangeListenerMethod(
            CGAnnotationList annotations, ModifierList modifiers);

    /**
     * @param annotations Annotations.
     * @param modifiers Modifiers.
     * 
     * @return a removePropertyChangeListener() method.
     */
    CGMethod createRemovePropertyChangeListenerNamedMethod(
            CGAnnotationList annotations, ModifierList modifiers);

    /**
     * @return a new toString() method.
     */
    CGMethod createToStringMethod();
}
